home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / dev / basic / PureBasic_Upd.lha / PureBasic_Update1.60 / PureBasic / Library SDK / PureBasic SDK.Readme
Encoding:
Text File  |  2000-09-10  |  5.0 KB  |  184 lines
  1.  
  2. ***********************************************************
  3. *
  4.   PureBasic Library SDK V1.1
  5. *
  6. ***********
  7.  
  8.  
  9.   Introduction:
  10.   -------------
  11.  
  12.   The PureBasic is mainly based on its third libraries which
  13.   allow it to handle differents objects very easely. These libs
  14.   have to be written in pure 680x0 or PowerPC assembler for
  15.   maximum speed and compactness. To achieve this, a set of
  16.   macros and constants have been designed to make the coder
  17.   life easier.
  18.  
  19.   Only the 680x0 package is available, as the PPC support is still
  20.   not finished. The macro file is designed for PhxAss, a very good
  21.   assembler which is located in the 'PureBasic:Compiler/' directory.
  22.  
  23.   You can create a library for 68000, 68020+ or any other processors
  24.   of the 680x0 family. You are free to use the FPU or not. BUT if a
  25.   library isn't compatible with the 'small' 68000, please tell it
  26.   in the documentation of your library.
  27.  
  28.   The libraries you made are under your copyright, if you are a regular
  29.   PureBasic user. So you can spread in any forms (freeware, shareware..).
  30.  
  31.  
  32.   The library structure:
  33.   ----------------------
  34.  
  35.   PureBasic libraries aren't standard Amiga linkable object,
  36.   so you can't reuse the code with another compiler. They are their
  37.   own structure to allow to split the library into little parts and
  38.   link only the needed one to the final executable. So you can
  39.   build a 100 Kb library with tons of functions, and if the
  40.   program use only a function, only this function will be linked.
  41.  
  42.   This suppose one thing: the code of each function MUST be relocatable
  43.   and fixed jump AREN'T allowed (or only if the part is inside the function).
  44.  
  45.   Each library has 2 parts:
  46.  
  47.     + The code, with functions
  48.     + The base of the library. This base is an area of memory you can
  49.     define to feed your need and which all functions could access later.
  50.     It's very handy to store some variables which could be used by
  51.     other functions. The access to this base memory will be done
  52.     trough the register 'a5'
  53.  
  54.   Example:
  55.  
  56.   ...Code part...
  57.  
  58.    base
  59.      Dc.l 0  ; First shared variable
  60.      Dc.l 0  ; Second one
  61.  
  62.  
  63.    To access the first variable in a function, just use:
  64.  
  65.    MOVE.l  (a5),<your reg>  ; Read the content of first variable
  66.    MOVE.l 4(a5),<your reg>  ; Read the content of second variable
  67.  
  68.    To write in these variables, use:
  69.  
  70.    MOVE.l xx,(a5)
  71.    MOVE.l xx,4(a5)
  72.  
  73.    Note: the base is always linked in the executable, so please,
  74.          don't do huge base !
  75.  
  76.  
  77.  
  78.   General rules:
  79.   --------------
  80.  
  81.   * You can't detroy the registers: a2/a3/a4/a7. Always preserve them.
  82.   * Always use continus registers (ie: d0, d1 and d2). Don't use the
  83.     registers in any orders if not needed (ie: d0, d5 and d7).
  84.   * The return value (if any) must be LONG typed ! So you want to
  85.     return a BYTE or WORD, use 'EXT' ASM keyword before returning.
  86.   * Never use absolute jump from one function to another.
  87.   * You're allowed to create a 'dc' zone for each function, so use
  88.     it ! Example:
  89.  
  90.         debugger 1
  91.  
  92.       Example:
  93.         MOVE.l $4,a6
  94.         LEA    Label1(pc),a0
  95.         RTS
  96.  
  97.       Label1:
  98.         DC.b "Hello...",0
  99.  
  100.         endfunc 1
  101.  
  102.  
  103.   The macros:
  104.   -----------
  105.  
  106.   Here is a quick description of the macro availables to build a library.
  107.   ALL the macros are needed ! None are optionals.
  108.  
  109.   ** name   "FunctionName", "QuickHelp"
  110.  
  111.   ** flags Flags
  112.  
  113.     Possible flags:
  114.  
  115.     'StringResult' or 'LongResult' or 'ByteResult' : Type of result for the function (default is 'word')
  116.     'NoBase' : If set, the function don't need to access the global base
  117.     'InLine' : If set, the function can be inlined and follow the inline rules
  118.  
  119.     Flags can be OR'ed together if needed
  120.  
  121.     ex: flags LongResult | NoBase | InLine
  122.  
  123.   ** amigalibs LibName, RegName, ...
  124.  
  125.     Possible LibName: _ExecBase, _IntuitionBase, _DosBase, _GraphicsBase
  126.     Possible RegName: d0 to d7, a0,a1,a6. Other are strictly forbidden !
  127.  
  128.  
  129.     Example: amigalibs _DosBase, a6
  130.  
  131.     Before the function call, the a6 register will be loaded with the
  132.     dos.library pointer.
  133.  
  134.  
  135.   ** params Reg_Type, ...
  136.  
  137.     The registers name and type with will contain the parameters:
  138.     d0_b : load a 'Byte' value into d0
  139.     d0_w : load a 'Word' value into d0
  140.     d0_l : load a 'Long' value into d0
  141.     d0_s : load a 'string address' into d0
  142.  
  143.     Note: You can't use the a2,a3,a4,a5,a6 registers !
  144.  
  145.     Ex: params d0_l, d1_l, a0_s ; a 3 parameters function
  146.  
  147.  
  148.   ** debugger Id_Function, LabelDebugger
  149.  
  150.   ** endfunc Id_Function
  151.  
  152.     The code of the functions must be between the 'debugger' and 'endfunc'
  153.     keywords. The 'Id_Function' must be the different for each function.
  154.  
  155.  
  156.   ** base
  157.  
  158.     declare the start of the base memory area
  159.  
  160.  
  161.   ** endlib
  162.  
  163.     finish the library
  164.  
  165.  
  166.   ** startdebugger
  167.  
  168.     Declare the debugger zone, with all debugger function within.
  169.  
  170.  
  171.   ** enddebugger
  172.  
  173.     Finish the debugger zone.
  174.  
  175.  
  176.   Just open the 'TagList.asm' example and look, it's not so hard !
  177.  
  178.             Good luck :-)
  179.  
  180.  
  181.   PS: the commandline to compile the source under PhxAss:
  182.  
  183.   PhxAss TagList.asm TO Ram:TagList OPT 3
  184.